Automated building, deploying and/or verifying of libraries

Neuron Power Engineer provides a tool for the automated building (=generation) and deployment of a library. This tool can also be used to verify the state of the library. 

Good to know

(grey lightbulb) The tool is intended for usage by an experienced user of Neuron Power Engineer.

(grey lightbulb)A condition for the successful usage of the tool is the knowledge of the action to be executed as it would be executed in the graphical user interface of Neuron Power Engineer.

(grey lightbulb)The output of the tool is in English only.
In this article:

Preparation

  1. Make sure that Neuron Power Engineer is installed. Have the following information prepared: 

    • The path to the Neuron Power Engineer installation directory 

    • The path to a directory that will be used as the workspace
      In case the directory does not exist, the tool creates it. If the optional parameter -checkEmptyWorkspace is used (see the description of this parameter below), the directory must be empty. 

    • The information for the libraries that should be built, deployed and/or verified

    • The path to the log configuration file (see below for more information)
      A sample configuration file is included in the installation of Neuron Power Engineer. 

  2. Open a command line: e.g. cmd.exe under Windows and navigate to the Neuron Power Engineer installation directory.  

Invocation

Parameters that are placed within [] are optional. That means, if you skip the parameter, the default behavior is applied (see below under "Description of parameters"). When you want to use the parameter, do not enter the character [ and ] (see the below examples). 

Invocation for automated building

NeuronPowerEngineerc --launcher.ini NeuronPowerEngineer.ini -application com.logicals.library.lc3lib.application [-noSplash] -libBuild [<LIBRARY-NAME__VERSION>] -projectPath <PROJECTPATH> -libraryDefinitionName <LIBCONFIGURATION-NAME> -data <WORKSPACE> [-checkEmptyWorkspace] -vmargs -Dlog4j.configuration=file:<LOG-CONFIGURATION>

Invocation for automated deploying

NeuronPowerEngineerc --launcher.ini NeuronPowerEngineer.ini -application com.logicals.library.lc3lib.application [-noSplash] -libDeploy [<LIBRARY-NAME__VERSION>] [-libDeployTo <TARGET_FOLDER>] -projectPath <PROJECTPATH> -libraryDefinitionName <LIBCONFIGURATION-NAME> -data <WORKSPACE> [-checkEmptyWorkspace] -vmargs -Dlog4j.configuration=file:<LOG-CONFIGURATION>

Invocation for automated verification

This verification checks whether the contents of the library have changed since it was created by redetermining the contents of the library files index.idx and index.md5  and comparing them with the rest of the library contents.

NeuronPowerEngineerc --launcher.ini NeuronPowerEngineer.ini -application com.logicals.library.lc3lib.application [-noSplash] -libCheck -fullLibraryName <FULL-LIBRARY-NAME> [-checkEmptyWorkspace] -vmargs -Dlog4j.configuration=file:<LOG-CONFIGURATION>

Combined invocation

It is possible to order the parameters as you like them. The best practice is to use the following order.

NeuronPowerEngineerc --launcher.ini NeuronPowerEngineer.ini -application com.logicals.library.lc3lib.application [-noSplash] -libBuild [<LIBRARY-NAME__VERSION>] -libDeploy [<LIBRARY-NAME__VERSION>] [-libDeployTo <TARGET_FOLDER>] -projectPath <PROJECTPATH> -libraryDefinitionName <LIBCONFIGURATION-NAME> -data <WORKSPACE> -libCheck -fullLibraryName <FULL-LIBRARY-NAME> [-checkEmptyWorkspace] -vmargs -Dlog4j.configuration=file:<LOG-CONFIGURATION>

(warning) Invoking the tool under Linux is not officially supported. However, if you want to try invoking the tool under Linux nevertheless, replace the part NeuronPowerEngineerc --launcher.ini NeuronPowerEngineer.ini -application of the above-mentioned invocation by NeuronPowerEngineer3 -application. The remaining part of the invocation is identical to the above-mentioned invocation.

Description of parameters:

Parameter

Description

Example

[<LIBRARY-NAME__VERSION>]

library to be build or deployed, as it is declared within the library configuration (specified by the parameter libraryDefinitionName <LIBCONFIGURATION-NAME>)
This parameter is optional. If it is not specified, all libraries that are declared within the library configuration will be built or deployed.

(warning) It is only possible to deploy a library, if this library has already been built (= generated). In case of a combined invocation, the building is automatically done before the deploying.

MyLibrary__1.1.0

<TARGET_FOLDER>

absolute path to a folder to which the library should be deployed
This parameter is optional. If it is not specified, the library is deployed using the library provider "Local file system" and its appropriate path. The path of this library provider be viewed and even changed in the preferences (menu Window, Preferences, group Library Provider, Library Provider).

By default, the following subfolder is specified for a library provider.

Library provider

Subfolder

Local file system

subfolder logi.cals\NeuronPowerEngineer\Libraries of the Windows user folder

Current project

subfolder library-releases of the project

 

C:\LC3Projects\MyProject\target

<FULL-LIBRARY-NAME>

name (incl. path and extension) of the library to be verified

This parameter might be the default path within a Neuron Power Engineer project where the library has already been generated. But it is also possible to specify a different path – in this case the path must contain the library.
Best practice is to use this tool to deploy a library with the parameter -libDeployTo <TARGET_FOLDER>. Then use this tool to verify the deployed library. In case of a combined invocation, the deploying is automatically done before the verification.

C:\LC3Projects\MyProject\target\MyLibrary__1.1.0.zip

<PROJECTPATH>

absolute path to the project
If the project already exists within the workspace (e.g. because there was a previous automated import of the project), it is also possible to specify the project name only.

C:\LC3Projects\MyProject

<LIBCONFIGURATION-NAME>

the library configuration which declares the libraries to be build or deployed
A library configuration is created by the command New – Library Configuration (context menu within the project explorer of Neuron Power Engineer).

(warning) Mind the following (see the example to the right):

  • The name must be specified with the correct capital and small letters (the name is case-sensitive).

  • The extension .lc3lib of the library configuration must be added to the name.

MyLibraries.lc3lib

<WORKSPACE>

absolute path to a workspace to which the project should be imported
Please note:

  • The directory of the workspace must not be located within a directory that is a Neuron Power Engineer project.

  • The directory might have to be empty – depending on the optional parameter -checkEmptyWorkspace (see the description of this parameter below).

  • After the invocation, the workspace will contain a reference to the Neuron Power Engineer project. That means that the Neuron Power Engineer project is not copied into the workspace.
    This is the same behavior as within the graphical user interface of Neuron Power Engineer when you would use the command Import... and the import type Existing Projects into Workspace with the disabled option Copy projects into workspace.

  • If the reference to the Neuron Power Engineer project already exists in the specified workspace because of a previous import, the import will not be done again in order to improve the performance of the tool. 

C:\temp\LC3Workspace

<LOG-CONFIGURATION>

path to the log configuration file
All messages of the tool will be output to the device as specified in the log configuration file.

C:\LC3LogConfig\log4j.xml

  • The parameter -noSplash is optional. If it is not specified, the splashscreen of Neuron Power Engineer is displayed after the invocation. 

  • The parameter -checkEmptyWorkspace is also optional. Specify this parameter to check whether the specified workspace is empty. The Neuron Power Engineer project will only be imported, if the workspace is empty.The default invocation (when this parameter is not specified) is that the Neuron Power Engineer project is always imported into the workspace – regardless whether the workspace is empty or not. If the Neuron Power Engineer project already exists within the workspace, the Neuron Power Engineer project is imported anew. 

  • The parameter -Dlog4j.configuration is also optional. However, Neuron recommends to specify this parameter so that log events are output. 
Example for combined invocation: Building and deploying all libraries of a library configuration 
NeuronPowerEngineerc --launcher.ini NeuronPowerEngineer.ini -application com.logicals.library.lc3lib.application -noSplash -libBuild -libDeploy -projectPath C:\LC3Projects\MyProject -libraryDefinitionName MyLibraries.lc3lib -data C:\temp\LC3Workspace -vmargs -Dlog4j.configuration=file:C:\LC3LogConfig\log4j.xml
Example for combined invocation: Building, deploying and verifying a specific library 
NeuronPowerEngineerc --launcher.ini NeuronPowerEngineer.ini -application com.logicals.library.lc3lib.application -noSplash -libBuild MyLibrary__1.1.0 -libDeploy MyLibrary__1.1.0 -libDeployTo C:\LC3Projects\MyProject\target -projectPath C:\LC3Projects\MyProject -libraryDefinitionName MyLibraries.lc3lib -data C:\temp\LC3Workspace -libCheck -fullLibraryName C:\LC3Projects\MyProject\target\MyLibrary__1.1.0.zip -vmargs -Dlog4j.configuration=file:C:\LC3LogConfig\log4j.xml

Log configuration file

This file is needed to configure the log4j logging mechanism. The file specifies how log events are output.

Sample log configuration file 
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration debug="false" xmlns:log4j='http://jakarta.apache.org/log4j/'>
 
  <!-- This configuration logs to console. -->
  <appender name="console" class="org.apache.log4j.ConsoleAppender">
    <param name="target" value="System.out"/>
    <param name="immediateFlush" value="true"/>
    <param name="encoding" value="UTF-8"/>
    <param name="threshold" value="info"/>
    <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} %-5p:  %m%n" />
    </layout>
  </appender>
 
  <!-- This configuration logs to a file, with more information than for the console. -->
  <appender name="file" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="file" value="C:\\temp\\logfile.log" />
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d{HH:mm:ss} %-5p [THREAD ID=%t] [Method:%M] %c{1}:%L - %m%n" />
    </layout>
  </appender>
  <root>
    <level value="INFO" />
    <appender-ref ref="console" />
    <appender-ref ref="file" />
  </root>
</log4j:configuration>

Troubleshooting

The file that is specified in the log configuration file contains information about the building, deploying and verification. If the building, deploying or verification has not been successful, fix the problem according to the following table.

Return code

Message

Cause

Solution

0

Library checksum validation successful (0)

 

 

-1

Library manager failed (Parameter Error, -1): Name

An argument or parameter is missing.

Invoke the tool as specified above.

-2

Library manager failed (-2): Project not found

The specified project does not exist.

Specify an existing project. Or invoke the tool with the absolute path for the project.

-6

Library manager failed (-6): Workspace not empty

The workspace already contains data (e.g. one or more Neuron Power Engineer projects).

Use an empty workspace or remove all existing data from the current one.
Alternate: Invoke the tool without the parameter -checkEmptyWorkspace.

-64

Library checksum validation failed (-64)

The library to be verified is corrupted.

Invoke the tool for a library that has been correctly built and deployed.

-65

Library build failed (-65)

The library could not be built.

Check, if there are additional messages detailing the error cause. Depending on these details:

Open the project in Neuron Power Engineer and fix the errors displayed in the Problems view.

Invoke the tool as specified above.

-66

Library deploy failed (-66)

The library could not be deployed.

Check the previous messages for error causes. Depending on these details:

Open the project in Neuron Power Engineer and fix the errors displayed in the Problems view.

Invoke the tool as specified above. Make sure that the library has already been built.

-127

Library manager (Details: exception message)

An unexpected error has occurred.

Contact Neuron.

The following messages might detail the error cause why the library could not be built:

  • Could not find a library with name and version: name

  • Could not find the library definition file: name

  • Model rule checking failed
    (info) You might want to use the tool for automated rule checking before building the library in order to make sure that the library objects are not violating any rules.